package com.kexio.config.service;

import java.util.List;
import java.util.Map;

import com.kexio.common.dto.Result;
import com.kexio.config.entity.DictData;

/**
 * 字典服务接口
 * 
 * @author Kexio Team
 * @since 1.0.0
 */
public interface DictService {
    
    /**
     * 根据字典类型获取字典列表
     * 
     * @param dictType 字典类型
     * @return 字典列表
     */
    List<DictData> getDictList(String dictType);
    
    /**
     * 根据字典类型和值获取标签
     * 
     * @param dictType 字典类型
     * @param dictValue 字典值
     * @return 字典标签
     */
    String getDictLabel(String dictType, String dictValue);
    
    /**
     * 根据字典类型和标签获取值
     * 
     * @param dictType 字典类型
     * @param dictLabel 字典标签
     * @return 字典值
     */
    String getDictValue(String dictType, String dictLabel);
    
    /**
     * 获取字典数据 (键值对格式)
     * 
     * @param dictType 字典类型
     * @return 字典数据 Map<value, label>
     */
    Map<String, String> getDictMap(String dictType);
    
    /**
     * 获取活跃的字典列表
     * 
     * @param dictType 字典类型
     * @return 字典列表
     */
    List<DictData> getActiveDictList(String dictType);
    
    /**
     * 获取默认字典项
     * 
     * @param dictType 字典类型
     * @return 默认字典项
     */
    DictData getDefaultDict(String dictType);
    
    /**
     * 保存字典数据
     * 
     * @param dictData 字典数据
     * @return 保存结果
     */
    Result<DictData> saveDict(DictData dictData);
    
    /**
     * 更新字典数据
     * 
     * @param dictData 字典数据
     * @return 更新结果
     */
    Result<DictData> updateDict(DictData dictData);
    
    /**
     * 删除字典数据
     * 
     * @param id 字典ID
     * @return 删除结果
     */
    Result<Boolean> deleteDict(String id);
    
    /**
     * 根据ID获取字典数据
     * 
     * @param id 字典ID
     * @return 字典数据
     */
    DictData getDictById(String id);
    
    /**
     * 检查字典值是否存在
     * 
     * @param dictType 字典类型
     * @param dictValue 字典值
     * @return 是否存在
     */
    boolean existsDictValue(String dictType, String dictValue);
    
    /**
     * 批量保存字典数据
     * 
     * @param dictDataList 字典数据列表
     * @return 保存结果
     */
    Result<Integer> batchSaveDict(List<DictData> dictDataList);
    
    /**
     * 根据字典类型删除所有字典数据
     * 
     * @param dictType 字典类型
     * @return 删除结果
     */
    Result<Boolean> deleteDictByType(String dictType);
    
    /**
     * 获取所有字典类型
     * 
     * @return 字典类型列表
     */
    List<String> getAllDictTypes();
    
    /**
     * 搜索字典数据
     * 
     * @param keyword 关键字
     * @return 字典数据列表
     */
    List<DictData> searchDict(String keyword);
    
    /**
     * 刷新字典缓存
     * 
     * @return 刷新结果
     */
    Result<Boolean> refreshDictCache();
    
    /**
     * 刷新指定类型的字典缓存
     * 
     * @param dictType 字典类型
     * @return 刷新结果
     */
    Result<Boolean> refreshDictCache(String dictType);
    
    /**
     * 获取层级字典 (树形结构)
     * 
     * @param dictType 字典类型
     * @return 层级字典列表
     */
    List<DictData> getHierarchicalDict(String dictType);
    
    /**
     * 根据父级值获取子级字典
     * 
     * @param dictType 字典类型
     * @param parentValue 父级值
     * @return 子级字典列表
     */
    List<DictData> getChildDict(String dictType, String parentValue);
    
    /**
     * 设置默认字典项
     * 
     * @param dictType 字典类型
     * @param dictValue 字典值
     * @return 设置结果
     */
    Result<Boolean> setDefaultDict(String dictType, String dictValue);
    
    /**
     * 更新字典排序
     * 
     * @param dictId 字典ID
     * @param newSort 新排序号
     * @return 更新结果
     */
    Result<Boolean> updateDictSort(String dictId, Integer newSort);
    
    /**
     * 启用/禁用字典项
     * 
     * @param dictId 字典ID
     * @param status 状态 (active/inactive)
     * @return 更新结果
     */
    Result<Boolean> updateDictStatus(String dictId, String status);
    
    /**
     * 导出字典数据
     * 
     * @param dictType 字典类型 (可选)
     * @return 字典数据
     */
    List<DictData> exportDict(String dictType);
    
    /**
     * 导入字典数据
     * 
     * @param dictDataList 字典数据列表
     * @param override 是否覆盖现有数据
     * @return 导入结果
     */
    Result<Integer> importDict(List<DictData> dictDataList, boolean override);
    
    /**
     * 获取字典统计信息
     * 
     * @return 统计信息
     */
    Map<String, Object> getDictStatistics();
}
